<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>throttle: common_schema documentation</title>
	<meta name="description" content="throttle: common_schema" />
	<meta name="keywords" content="throttle: common_schema" />
	<link rel="stylesheet" type="text/css" href="css/style.css" />
</head>

<body>
	<div id="main">
		<div id="header">
			<h1>common_schema</h1> <strong>2.2</strong> documentation
			<div class="subtitle">DBA's framework for MySQL</div>
		</div>
		<div id="contentwrapper">
			<div id="content">
				<h2><a href="throttle.html">throttle</a></h2>	
<h3>NAME</h3>
throttle(): Throttle current query by periodically sleeping throughout its execution.
<h3>TYPE</h3>
Function

<h3>DESCRIPTION</h3>
<p>
	This function sleeps an amount of time proportional to the time the query executes, on a per-lap basis.
	That is, time is measured between two invocations of this function, 
	and that time is multiplied by throttle_ratio to conclude the extent of throttling.
</p>
<p>
	The <i>throttle()</i> function is introduced as an easy means to alleviate the load of a heavy-weight query, by
	injecting sleep time periods into the query's execution; periods where query is not consuming CPU nor performing
	I/O operations. During such sleep periods, other queries can more easily compete for such resources.
</p>
<p>
	The function essentially increases the total runtime of the query.
</p>
<p>
	Due to the fact throttling is done within the query itself, some resources taken by query's execution are not released
	throughout the sleep periods. Namely, no locks nor memory are released for the entire duration of the query.  
</p>
<p>
	Whether the function should in fact throttle depends on current query execution time, and, so as to alleviate the
	overhead of this function itself, only computed once in a <strong>1,000</strong> runs. 
</p>
<p>
	<i>throttle()</i> returns the number of seconds spent sleeping on this call of the function. The number may be <strong>0</strong>
	if no throttling took place (either the like event of <i>not being</i> a one in a <strong>1,000</strong> execution,
	or the case where query lap time is too small to consider throttling).
</p>

<h3>SYNOPSIS</h3>
<p>
<blockquote><pre>throttle(throttle_ratio DOUBLE)
  RETURNS DOUBLE</pre></blockquote>
</p>
<p>
  Input:
  <ul>
    <li>
    	<strong>throttle_ratio</strong>: ratio by which to throttle, or extend total query time.
    	<br/>Query time is extended by multiplying given arguemnt with original query time.
    	<br/>For example, <strong>throttle_ratio</strong> value of <strong>1</strong> will double the
    	total execution time, since it adds one unit of query execution time.
    	<br/><strong>throttle_ratio</strong> of <strong>0.3</strong> will make the query
    	execute for <strong>30%</strong> more time, to the total of <strong>130%</strong> the original time.
	</li>
  </ul>
</p>
<h3>EXAMPLES</h3>
	<p>
		Compare query runtime with and without throttling. Roughly double the query's execution time
		by providing with a <strong>throttle_ratio</strong> value of <strong>1</strong>.
	</p>
	<blockquote><pre>mysql&gt; SELECT Id, Name, sleep(0.001) from world.City ORDER BY Population DESC;
+------+------------------------------------+--------------+
| Id   | Name                               | sleep(0.001) |
+------+------------------------------------+--------------+
| 1024 | Mumbai (Bombay)                    |            0 |
| 2331 | Seoul                              |            0 |
|  206 | São Paulo                          |            0 |
| 1890 | Shanghai                           |            0 |
|  939 | Jakarta                            |            0 |
...
| 2316 | Bantam                             |            0 |
| 3538 | Città del Vaticano                 |            0 |
| 3333 | Fakaofo                            |            0 |
| 2317 | West Island                        |            0 |
| 2912 | Adamstown                          |            0 |
+------+------------------------------------+--------------+
<strong>4079 rows in set (4.53 sec)</strong>
</pre></blockquote>
	<blockquote><pre>mysql&gt; SELECT Id, Name, sleep(0.001), throttle(1) from world.City ORDER BY Population DESC;
+------+------------------------------------+--------------+-------------+
| Id   | Name                               | sleep(0.001) | throttle(1) |
+------+------------------------------------+--------------+-------------+
| 1024 | Mumbai (Bombay)                    |            0 |           0 |
| 2331 | Seoul                              |            0 |           0 |
|  206 | São Paulo                          |            0 |           0 |
| 1890 | Shanghai                           |            0 |           0 |
|  939 | Jakarta                            |            0 |           0 |
...
| 2316 | Bantam                             |            0 |           0 |
| 3538 | Città del Vaticano                 |            0 |           0 |
| 3333 | Fakaofo                            |            0 |           0 |
| 2317 | West Island                        |            0 |           0 |
| 2912 | Adamstown                          |            0 |           0 |
+------+------------------------------------+--------------+-------------+
<strong>4079 rows in set (8.69 sec)</strong>
</pre></blockquote>


<h3>ENVIRONMENT</h3>
MySQL 5.1 or newer


<h3>SEE ALSO</h3>
<a href="query_laptime.html">query_laptime()</a>,
<a href="query_runtime.html">query_runtime()</a>,
<a href="query_script_throttle.html">QueryScript throttle</a>

<h3>AUTHOR</h3>
Shlomi Noach
				<br/>
			</div>
			<div id="sidebarwrapper">
				<div id="search">
					Search online documentation
					<form id="search_form" name="search_form" method="GET" 
						action="http://www.google.com/search" 
						onsubmit="document.forms['search_form']['q'].value = 'site:http://common-schema.googlecode.com/svn/trunk/common_schema/doc/html/ '+document.forms['search_form']['search_term'].value;">
						<input type="text" name="search_term" value=""/>
						<input type="hidden" name="q" value=""/>
						<input type="submit" value="go"/>						
					</form>
				</div>
				<div id="menu">
					<ul>
						<li><a title="Introduction" href="introduction.html">Introduction</a></li>
						<li><a title="Documentation" href="documentation.html">Documentation</a></li>
						<li><a title="Download" href="download.html">Download</a></li>
						<li><a title="Install" href="install.html">Install</a></li>
						<li><a title="Risks" href="risks.html">Risks</a></li>
					</ul>						
					<h3>QUERY SCRIPT</h3>
					<ul>
						<li><a title="QueryScript" href="query_script.html">QueryScript</a></li>
						<li><a title="Execution" href="query_script_execution.html">Execution</a></li>
						<li><a title="Flow control" href="query_script_flow_control.html">Flow control</a></li>
						<li><a title="Statements" href="query_script_statements.html">Statements</a></li>
						<li><a title="Expressions" href="query_script_expressions.html">Expressions</a></li>
						<li><a title="Variables" href="query_script_variables.html">Variables</a></li>
					</ul>						
					<h3>DEBUG</h3>
					<ul>
						<li><a title="rdebug" href="rdebug.html">rdebug</a></li>
						<li><a title="rdebug API" href="rdebug_api.html">rdebug API</a></li>
						<li><a title="rdebug workflow" href="rdebug_workflow.html">Workflow</a></li>
					</ul>						
					<h3>ROUTINES</h3>
					<ul>
						<li><a title="Execution &amp; flow control" href="execution_routines.html">Execution & flow control</a></li>
						<li><a title="General" href="general_routines.html">General</a></li>
						<li><a title="Process" href="process_routines.html">Process</a></li>
						<li><a title="Query analysis" href="query_analysis_routines.html">Query analysis</a></li>
						<li><a title="Schema analysis" href="schema_analysis_routines.html">Schema analysis</a></li>
						<li><a title="Security" href="security_routines.html">Security</a></li>
						<li><a title="Text" href="text_routines.html">Text</a></li>
						<li><a title="Time &amp; date" href="temporal_routines.html">Time & date</a></li>
						<li><a title="Charting" href="charting_routines.html">Charting</a></li>
					</ul>
					<h3>VIEWS</h3>
					<ul>
						<li><a title="Schema analysis" href="schema_analysis_views.html">Schema analysis</a></li>
						<li><a title="Data dimension" href="data_dimension_views.html">Data dimension</a></li>
						<li><a title="Process" href="process_views.html">Process</a></li>
						<li><a title="Security" href="security_views.html">Security</a></li>
						<li><a title="Monitoring" href="monitoring_views.html">Monitoring</a></li>
						<li><a title="InnoDB Plugin" href="innodb_plugin_views.html">InnoDB Plugin</a></li>
						<li><a title="Percona server" href="percona_server_views.html">Percona Server</a></li>
						<li><a title="TokuDB" href="tokudb_views.html">TokuDB</a></li>
					</ul>						
					<h3>DATA</h3>
					<ul>
						<li><a title="tables" href="tables.html">Tables</a></li>
						<li><a title="variables" href="variables.html">Variables</a></li>
					</ul>						
					<h3>META</h3>
					<ul>
						<li><a title="Help" href="help.html">help</a></li>
						<li><a title="Metadata" href="metadata.html">metadata</a></li>
						<li><a title="status" href="status.html">status</a></li>
					</ul>						
				</div>
			</div>	
			<div class="clear">&nbsp;</div>
			
			<div id="footnote" align="center">
				<a href="">common_schema</a> documentation
			</div>
		</div>
	</div>
</body>
</html>
